home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 44 / Amiga Format CD44 (1999-08-26)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-10].iso / -serious- / misc / srename / docs / srename.doc < prev    next >
Text File  |  1999-07-12  |  60KB  |  1,636 lines
  1.  
  2. *******************************************************************************
  3.                          SRENAME 2.900  USERS MANUAL
  4.               Copyright (C) 1996-1999 Constantinos Nicolakakis
  5. *******************************************************************************
  6.  
  7.  
  8. INTRODUCTION :
  9.  
  10. The philosophy behind SRename is to give you a CLI command with relatively few,
  11. but versatile functions that can be combined in many ways to provide whatever
  12. renaming operation is needed by the user, rather than providing dozens of
  13. specialised renaming options that limit the renaming operations that can be
  14. performed, to what the programmer had in mind when he was designing the command
  15. and are difficult to remember by the user.
  16. SRename can easily replace the original Rename command but I wouldn't recommend
  17. that because SRename's behaviour is not identical to the original command.
  18. You will probably find SRename most useful at renaming a lot of filenames at
  19. once, as it supports wildcards, multiple filenames and recursion.
  20.  
  21. Some of SRename's advantages:
  22.  
  23.  * Selector-Action keyword separation that allows building specialized
  24.    functions easily.
  25.  * Total control over recursion.
  26.  * Wildcard and multiple filename support.
  27.  * Optional wildcard for directory selection in recursion.
  28.  * Can isolate selected parts of the filename for modification with the use
  29.    of the selector keywords.
  30.  * Executes multiple actions in one go.
  31.  * Performs intelligent renumbering with automatic checking for filename
  32.    clashes.
  33.  * Supports long filenames on filesystems that allow them.
  34.  * Can also modify filename comments.
  35.  * It's free.
  36.  
  37.  
  38. PROGRAM STATUS :
  39.  
  40. SRename is freeware. Permission is granted to distribute free of charge,
  41. in unchanged form, provided this documentation file is accompanied with the
  42. program.
  43. Permission is granted to include on freely distributable software libraries
  44. such as Aminet CD-ROMs.
  45. The author's permission is required if SRename is to be distributed as a part
  46. of a commercial application.
  47. Although I'm quite confident that SRename contains no major bugs, I can't
  48. guarantee that it is completely bug-free, and do not accept any responsibility
  49. of any damage this program could cause directly or indirectly.
  50.  
  51.  
  52. REQUIREMENTS :
  53.  
  54. Amiga with kickstart 2 or higher.
  55.  
  56.  
  57. TECHNICAL :
  58.  
  59. SRename is written in C++ and was compiled with SAS C 6.58. It uses C++
  60. features like object classes to achieve code reusability, memory management
  61. reliability and good program design.
  62. Memory is allocated dynamically in pages, to avoid high memory usage.
  63. Average memory usage is around 100-200 Kb when recursing through large disks
  64. or partitions.
  65. It always uses buffers when renaming more than one filename as the Ram-Disk's
  66. filesystem has a bug that makes unbuffered renaming with pattern matching
  67. problematic.
  68. SRename has been tested successfully with Enforcer and MungWall on my A4000 
  69. 060 @50 / 604e @200, kickstart 3.0, 72 MB RAM.
  70.  
  71.  
  72. INSTALLATION :
  73.  
  74. Just copy SRename to your C: directory.
  75.  
  76.  
  77. INTERFACE CHANGES/ADDITIONS :
  78.  
  79. The command interface of SRename is not 100% backwards compatible with previous
  80. versions, as some functions have been replaced by others along the way, and
  81. some improvements have been made to the command interface itself to make it
  82. more consistent and easier to use.
  83. To make it easier to upgrade to newer versions I include a button bank and
  84. a start menu for use with Directory Opus 5, that is set up to work with the
  85. latest version of SRename.
  86.  
  87. Since 2.900:
  88.  
  89. Added the COMMENT selector to allow the modification of filename comments
  90. and the TOCOMMENT and TOFILENAME keywords to manage the redirection of the
  91. resulting filename or comment.
  92.  
  93. Since 2.850:
  94.  
  95. Removed the APPEND and FROMEND keywords to simplify the command interface.
  96. Their function is now performed by giving negative values to the AT and WORD
  97. keywords respectively.
  98. Note that the value that AT receives is now higher by 1. For example instead
  99. of giving AT 0 to place a string at the beginning of a filename, you should
  100. now give AT 1 to do that.
  101. Also gone is the limitation that wouldn't allow the insertion of a string at
  102. the end of a filename with normal insertion, that is by not using the append
  103. mode (AT with negative values).
  104.  
  105. For example: 
  106. APPEND is replaced by AT -1
  107. AT 2 APPEND is replaced by AT -2
  108. WORD 1 FROMEND is replaced by WORD -1
  109.  
  110. Since 2.710:
  111.  
  112. Single character mode is now automatically activated if the string given after
  113. MATCH consists of only one character. This makes the colon ':' that indicates
  114. single character mode unnecessary when matching only a single character.
  115.  
  116. Since 2.700:
  117.  
  118. LENGTH action removed. It can easily be replaced by MID <num> DELETE.
  119. Added WORD selector, supported by FROMEND, INCLSEP and WSEP.
  120.  
  121. Since 2.540:
  122.  
  123. MATCH additions: multiple match string support, single character mode, and
  124. character code mode.
  125. DELCHARS was removed as it can be replaced by MATCH :<chars> DELETE.
  126. SWAP now takes into account the PREFIX/MAIN/SUFFIX selectors, so that parts
  127. other than just the extremest can be swapped.
  128.  
  129. Since 2.520:
  130.  
  131. The TO keyword is no longer needed to perform simple renaming, so you can now
  132. type 'SRename oldname newname' to rename 'oldname' as 'newname'.
  133. The FILENAME keyword was renamed as FROM (same as the original rename command).
  134.  
  135. Since 2.510:
  136.  
  137. ICONS option was added to automatically rename .info files in single or
  138. multiple filename mode (not in wildcard mode).
  139.  
  140. Since 2.500:
  141.  
  142. New keywords:
  143.  
  144.  - DO
  145.  - SKIP
  146.  - BEFORE
  147.  - AFTER
  148.  - REVMATCH
  149.  - AT
  150.  - APPEND
  151.  - UPDATE
  152.  - UPTO
  153.  
  154. Removed keywords:
  155.  
  156.  - DELBASE (is replaced by BASENAME "")
  157.  
  158. Additional parameters were removed from keywords:
  159.  
  160.  - MATCH (moved to DO, SKIP, BEFORE, AFTER, REVMATCH)
  161.  - INSERT (moved to AT, APPEND)
  162.  - RENUMBER (moved to UPTO)
  163.  
  164. Other changes:
  165.  
  166. LEFT-RIGHT is not used anymore to set the position of the number within the
  167. basename in renumbering mode. Instead the AT and APPEND keywords are used for
  168. that purpose.
  169. The following keywords now have different full names:
  170.  - PRE is PREFIX
  171.  - SUF is SUFFIX
  172.  - LEN is LENGTH
  173. The following keywords now have abbreviations:
  174.  - PREFIX (PR)
  175.  - MAIN (MA)
  176.  - SUFFIX (SU)
  177.  - LEFT (L)
  178.  - MID (M)
  179.  - RIGHT (R)
  180.  - QUIET (Q)
  181.  
  182. Read each function's description for details about it's syntax.
  183.  
  184.  
  185. USAGE :
  186.  
  187. SRename FROM/A/M,TO=AS/K,RLEVEL=RL/N,SLEVEL=SL/N,DIRPAT=DP/K,ALLDIRS=AD/S,
  188. RECURSE=RC/S,NODIRS=ND/S,NOFILES=NF/S,ICONS=IC/S,DOT/K,WSEP=WS/K,COMMENT=CO/S,
  189. PREFIX=PR/S,MAIN=MA/S,SUFFIX=SU/S,WORD=WD/N,INCLSEP=IS/N,LEFT=L/K,MID=M/K,
  190. RIGHT=R/K,MATCH=MT/K,DO/N,SKIP=SK/N,BEFORE=BF/S,AFTER=AF/S,REVMATCH=RM/S,
  191. EXCLUDE=XC/S,EXIST=XS/S,CASESENS=CS/S,TOFILENAME=TF/S,TOCOMMENT=TC/S,
  192. UPPER=UP/S,LOWER=LW/S,UPAFTERSPC=US/S,INSERT=IN/K,AT/N,UPDATE=UD/S,DELETE=DL/S,
  193. SWAP=SW/S,LSHIFT=LS/S,RSHIFT=RS/S,UNIFY=UN/S,CONV8+3=8+3/S,RENUMBER=RN/K,
  194. UPTO=UT/N,STEP=ST/N,PLACES=PL/N,INVERT=IV/S,BASENAME=BN/K,PREFIRST=PF/S,
  195. NODIROUT=NDO/S,QUIET=Q/S:
  196.  
  197.  
  198. Short description of keywords :
  199.  
  200.           FROM <string(s)> : filename(s) to rename
  201.  
  202.                TO <string> : new string that replaces the selected characters,
  203.                              and/or destination path
  204.  
  205.            RLEVEL <number> : set the maximum level of recursion
  206.  
  207.            SLEVEL <number> : set the starting level of recursion
  208.  
  209.            DIRPAT <string> : match pattern for entering directories
  210.  
  211.                    ALLDIRS : make the DIRPAT pattern be used and beyond the
  212.                              starting level of recursion
  213.  
  214.                    RECURSE : set full recursion
  215.  
  216.                     NODIRS : no directories are renamed
  217.  
  218.                    NOFILES : no files are renamed
  219.  
  220.                      ICONS : rename .info files automatically
  221.  
  222.            DOT <character> : set the separator of prefix,main,suffix
  223.  
  224.        WSEP <character(s)> : set the separator of words
  225.  
  226.                    COMMENT : select the comment of the filename
  227.  
  228.                     PREFIX : select the prefix
  229.  
  230.                       MAIN : select the main part
  231.  
  232.                     SUFFIX : select the suffix
  233.  
  234.   WORD <number>,[<number>] : select the specified word
  235.  
  236.           INCLSEP <number> : also select the word's separating chars
  237.  
  238.   LEFT <number>,[<number>] : select characters from the left
  239.  
  240.  MID [<number>],[<number>] : select characters in the middle
  241.  
  242.  RIGHT <number>,[<number>] : select characters from the right
  243.  
  244.             MATCH <string> : select the part that matches the string
  245.  
  246.                DO <number> : number of matches to perform
  247.  
  248.              SKIP <number> : number of matches to skip before starting
  249.  
  250.                     BEFORE : select the characters before the matched string
  251.  
  252.                      AFTER : select the characters after the matched string
  253.  
  254.                   REVMATCH : look for matches from the end of the filename
  255.  
  256.                    EXCLUDE : invert the selection process
  257.  
  258.                      EXIST : select a filename component only if it exists
  259.  
  260.                   CASESENS : enable case-sensitive matching
  261.  
  262.                 TOFILENAME : redirect the result to the filename
  263.  
  264.                  TOCOMMENT : redirect the result to the comment
  265.  
  266.                      UPPER : make the selected characters uppercase
  267.  
  268.                      LOWER : make the selected characters lowercase
  269.  
  270.                 UPAFTERSPC : make uppercase the character after a space
  271.  
  272.            INSERT <string> : insert a string into the filename
  273.  
  274.                AT <number> : set the position for the string to insert
  275.  
  276.                     UPDATE : insert a string only if it does not exist in the
  277.                              specified position
  278.  
  279.                     DELETE : delete the selected characters
  280.  
  281.                       SWAP : swap the selected segments
  282.  
  283.                     LSHIFT : shift filename segments to the left
  284.  
  285.                     RSHIFT : shift filename segments to the right
  286.  
  287.                      UNIFY : unify the selected segments
  288.  
  289.                    CONV8+3 : convert to MS-DOS filename format
  290.  
  291.          RENUMBER <number> : renumber a filename sequence to start with the
  292.                              given number
  293.  
  294.              UPTO <number> : renumber up to that number
  295.  
  296.              STEP <number> : set the renumber step value
  297.  
  298.            PLACES <number> : set the renumber number-format
  299.  
  300.                     INVERT : perform inverted renumbering
  301.  
  302.          BASENAME <string> : set the renumber basename
  303.  
  304.                   PREFIRST : set the prefix segment first
  305.  
  306.                   NODIROUT : no directory name output
  307.  
  308.                      QUIET : no output at all
  309.  
  310.  
  311. A detailed description of the above keywords can be found below. Most keywords
  312. have an abbreviation which is the one in parentheses after their full name.
  313.  
  314.  
  315. *******************************************************************************
  316.                               FILE/DIR SELECTORS:
  317. *******************************************************************************
  318.  
  319. The following keywords define which files or directories will be renamed,
  320. according to their name, file or dir type, directory tree level, and the
  321. directory name that are in.
  322.  
  323.  
  324. FROM <filename(s)> :
  325. The given file(s) or dir(s) are renamed. If just a directory or volume is
  326. supplied, all its files are renamed. If instead of a filename, a pattern
  327. (wild-card) is given, only files or dirs that match this pattern will be
  328. renamed.
  329. Multiple patterns can be supplied. Note that you don't actually have to type
  330. 'FROM' in the command line.
  331.  
  332. Examples:
  333. > SRename C LW : Make C lowercase regardless of type (file or dir)
  334.  
  335. > SRename C/ LW : Make all files and dirs in C lowercase
  336.  
  337. > SRename C:d* UP : Make all files and dirs in C that begin with 'd' uppercase
  338.  
  339. -------------------------------------------------------------------------------
  340.  
  341. RLEVEL (RL) <recursion level value> :
  342. Sets the level of recursion. If this is 1, only subdirectories in the current
  343. directory will be entered.
  344. The default recursion level is 0 (no recursion).
  345.  
  346. Example:
  347. > SRename SYS:Games/a* LW RL 3 : Make all files in SYS:Games that begin with
  348. 'a' and in subdirectories up to 3 levels deep lowercase.
  349.  
  350. -------------------------------------------------------------------------------
  351.  
  352. SLEVEL (SL) <starting level value> :
  353. Sets the starting level of recursion. Files and directories in a tree level
  354. lower than the specified will not be entered. Also sets full recursion if a
  355. RLEVEL parameter is not given. The default starting level is 1.
  356. Note that the value of SLEVEL can not be greater than the value of RLEVEL.
  357.  
  358. Example:
  359. > SRename SYS: UP SL 2 : Make all filenames in SYS: uppercase, except for the
  360. filenames in the root directory.
  361.  
  362. -------------------------------------------------------------------------------
  363.  
  364. RECURSE    (RC) :
  365. Sets full recursion. All directories in the directory tree will be entered.
  366. It is overridden by RLEVEL and can also be set by ALLDIRS.
  367.  
  368. Example:
  369. > SRename SYS:Games/a* LW RC : Make all files in SYS:Games that begin with 'a'
  370. lowercase in all subdirectories.
  371.  
  372. -------------------------------------------------------------------------------
  373.  
  374. DIRPAT (DP) <wildcard pattern> :
  375. Determines which directories in a given path are to be entered to rename their
  376. contents according to the specified pattern.
  377. This parameter implies that recursion is active, if not it sets the level of
  378. recursion to 1.
  379. Note that the DIRPAT pattern is used only once for the directories that exist
  380. in the directory that renaming begins.
  381. If you want the DIRPAT pattern to be used all the way when recursing you must
  382. give the ALLDIRS keyword.
  383.  
  384. Examples:
  385. > SRename SYS:Data/*z DP project* DL SU : Remove the suffix from all the
  386. filenames in SYS:Data that end with 'z' and from the filenames in the
  387. subdirectories of SYS:Data that begin with 'project'.
  388.  
  389. > SRename SYS:Data/*z DP project* DL SU RC : Same as the previous example but
  390. acts on filenames in all subdirectories that are contained in directories that
  391. begin with 'project'.
  392.  
  393. -------------------------------------------------------------------------------
  394.  
  395. ALLDIRS (AD) :
  396. Makes the DIRPAT pattern be used with all directories that are encountered,
  397. not just with those in the starting level. A directory is entered for renaming
  398. to take place, only if it matches the DIRPAT pattern.
  399. ALLDIRS sets full recursion if a RLEVEL parameter is not given.
  400.  
  401. Examples:
  402. > SRename SYS:Data/*z DP project* DL SU AD : Remove the suffix from all
  403. the filenames in SYS:Data that end with 'z' and in all subdirectories of
  404. SYS:Data that begin with 'project'.
  405.  
  406. > SRename SYS:Data/*z DP project* DL SU RL 2 : same as the previous
  407. example but only acts on subdirectories of SYS:Data that begin with 'project'
  408. in a depth of up to 2 levels.
  409.  
  410. -------------------------------------------------------------------------------
  411.  
  412. NODIRS (ND) :
  413. Do not rename any directories. Only files are renamed.
  414.  
  415. Example:
  416. > SRename Work/Data/ UP ND : Make all the filenames in Work/Data uppercase.
  417. Directory names are not renamed.
  418.  
  419. -------------------------------------------------------------------------------
  420.  
  421. NOFILES (NF) :
  422. Do not rename any files. Only directories are renamed.
  423.  
  424. Example:
  425. > SRename Work/Data LW NF : Make all the dirnames in Work/Data lowercase.
  426. Filenames are not renamed.
  427.  
  428. Note: if both NODIRS and NOFILES are given, only NODIRS will remain active.
  429.  
  430. -------------------------------------------------------------------------------
  431.  
  432. ICONS (IC) :
  433. When in single or multiple filename mode or in renumbering mode the icon files
  434. (.info files) are renamed automatically even if they weren't specified in the
  435. filename list.
  436. Note that the way this option works is that the icon gets exactly the same
  437. filename that was given to the file that the icon accompanies.
  438. The icon's filename itself is not taken into account.
  439. If the file of the accompanying icon couldn't be found then the icon's filename
  440. will not be modified.
  441.  
  442. As of this version ICONS can also be used with wildcards. When this happens
  443. the wildcard pattern is modified so that it will exclude icon filenames so that
  444. icon filenames will not be modified twice.
  445.  
  446. Examples:
  447. > SRename tools/lacer tools/prepcard UP IC : Make 'lacer' and 'prepcard'
  448. uppercase including their icons' filenames.
  449. output:
  450. "lacer" renamed as "LACER"
  451. "lacer.info" renamed as "LACER.info"
  452. "prepcard" renamed as "PREPCARD"
  453. "prepcard.info" renamed as "PREPCARD.info"
  454.  
  455. >SRename tools/p#? UP IC : Make all filenames starting with 'p' and their
  456. icons' filenames uppercase.
  457. output:
  458. "PrintFiles" renamed as "PRINTFILES"
  459. "PrintFiles.info" renamed as "PRINTFILES.info"
  460. "PrepCard" renamed as "PREPCARD"
  461. "PrepCard.info" renamed as "PREPCARD.info"
  462.  
  463. >SRename picture1 RN 10 IC : Renumber files from picture1 and up, including
  464. their icons.
  465. output:
  466. "picture1" renamed as "picture10"
  467. "picture1.info" renamed as "picture10.info"
  468. "picture2" renamed as "picture11"
  469. "picture2.info" renamed as "picture11.info"
  470. "picture3" renamed as "picture12"
  471. "picture3.info" renamed as "picture12.info"
  472.  ....
  473.  
  474. -------------------------------------------------------------------------------
  475.  
  476. COMMENT (CO) :
  477. This is a special selector that makes SRename select the filename's comment
  478. for modification instead of the filename itself.
  479. All the other selectors and actions can then be applied to the comment and the
  480. result of the modification will go to the filename's comment unless it is
  481. redirected by the TOFILENAME keyword.
  482. None of the renumbering actions however can be used with COMMENT.
  483. Using COMMENT with such an action will be the same as using the TOCOMMENT
  484. keyword. (see below)
  485.  
  486. Examples:
  487. >SRename pic.iff CO UP : Make the comment of 'pic.iff' uppercase.
  488. output:
  489. Comment of "pic.iff" changed from "created with lightwave" to "CREATED WITH 
  490. LIGHTWAVE"
  491.  
  492. >SRename Data:pics/ CO DL : Delete all the comments from the filenames in the
  493. 'Data:pics/' directory.
  494.  
  495. >SRename roms/ CO MT "MAME" TO "M.A.M.E." : Replace all occurences of 'MAME'
  496. in the comments of the filenames in 'roms' with 'M.A.M.E.'
  497.  
  498.  
  499. *******************************************************************************
  500.                               REDIRECTION KEYWORDS
  501. *******************************************************************************
  502.  
  503. TOFILENAME (TF) :
  504. This keyword is implied when performing filename renaming. It's main purpose
  505. is to redirect the modified or unmodified comment to the filename instead.
  506. If the user wants the current comment to be modified as well as the filename
  507. then the TOCOMMENT keyword must also be given.
  508. If a filename's comment contains characters that denote a path then only the
  509. filename part of the comment will go to the filename.
  510.  
  511. Examples:
  512. >SRename sample.iff CO TF : 'sample.iff' will be renamed as it's comment.
  513. output:
  514. "sample.iff" renamed as "created with SFX"
  515.  
  516. >SRename sample.iff CO UP TF TC : Makes the comment of 'sample.iff' uppercase
  517. and will also use it to rename 'sample.iff'.
  518. output:
  519. Comment of "sample.iff" changed from "created with SFX" to "CREATED WITH SFX"
  520. "sample.iff" renamed as "CREATED WITH SFX"
  521.  
  522. -------------------------------------------------------------------------------
  523.  
  524. TOCOMMENT (TC) :
  525. This keyword is implied when modifying filename comments. It's main purpose is
  526. to redirect the modified or unmodified filename to the comment instead.
  527. If the user wants the filename to be modified as well as the comment then the
  528. TOFILENAME keyword must also be given.
  529.  
  530. Note that when both TOFILENAME and TOCOMMENT are given with the ICONS keyword
  531. then only the filenames of icons is modified and not their comments.
  532. Files other than icons will get both their filename and comment modified in
  533. such a case.
  534.  
  535. Examples:
  536. >SRename brush1.bsh SU TO iff TF TC : Puts 'iff' to the filename suffix and
  537. also copies the new filename to the comment.
  538. output:
  539. Comment of "brush1.bsh" changed from "" to "brush1.iff"
  540. "brush1.bsh" renamed as "brush1.iff"
  541.  
  542. >SRename brush1.bsh TC : Copies the filename to the comment.
  543. output:
  544. Comment of "brush1.bsh" changed from "" to "brush1.bsh"
  545.  
  546.  
  547. *******************************************************************************
  548.                   CHARACTER SELECTORS:  (in order of evaluation)
  549. *******************************************************************************
  550.  
  551. The following keywords define which parts of the filename will be affected by
  552. the action keywords that will follow. The selection can be done according to
  553. the position of the characters or the characters themselves.
  554.  
  555.  
  556. PREFIX (PR) :
  557. Select the prefix (leftmost part) for modification.
  558.  
  559. MAIN (MA) :
  560. Select the main part (middle part) for modification.
  561.  
  562. SUFFIX (SU) :
  563.  Select the suffix (rightmost part) for modification.
  564.  
  565. Specifying one of the above selectors does not cancel the others. Note that
  566. if SRename receives a filename with only two components it regards that the
  567. filename has no prefix.
  568. The prefix component is filled only if the filename has 3 or more components,
  569. or with 2 components if PREFIRST is specified, which forces prefix-main to be
  570. filled instead of main-suffix.
  571.  
  572. Here are some examples on how different filenames fill the PREFIX-MAIN-SUFFIX
  573. components:
  574.  
  575.      Filename          PREFIX          MAIN          SUFFIX
  576.  ----------------     --------       --------       --------
  577.  test              :   -empty-         test          -empty-
  578.  
  579.  001.test.pic.gif  :    001            test.pic       gif
  580.  
  581.  test.pic.gif      :    test           pic            gif
  582.  
  583.  001.test          :   -empty-         001            test
  584.  
  585.  001.test PREFIRST :    001            test          -empty-
  586.  
  587. Examples:
  588. > SRename Work:#? SU ilbm XS : Replaces the contents of the suffix of
  589. every filename in Work: with 'ilbm', if they have a suffix.
  590.  
  591. > SRename files/backup.lzx MA UP : Makes the main component uppercase.
  592. output:
  593. "backup.lzx" renamed as "BACKUP.lzx"
  594.  
  595. > SRename mod.techno PR UP PF : Forces PREFIX to be filled before SUFFIX and
  596. makes the prefix uppercase.
  597. output:
  598. "mod.techno" renamed as "MOD.techno"
  599.  
  600. > SRename TheLastBallad.s3m SU UP : Makes the suffix uppercase.
  601. output:
  602. "TheLastBallad.s3m" renamed as "TheLastBallad.S3M"
  603.  
  604. -------------------------------------------------------------------------------
  605.  
  606. WORD (WD) <starting word number>,[number of words to select] :
  607. Select a word within the filename. A word is determined by spaces by default,
  608. unless the word separator is changed with the WSEP keyword.
  609. Words are selected from the start of the filename unless the starting word
  610. number is negative.
  611. For example WORD -1 selects the last word of the filename.
  612. If the second parameter is also given then consecutive words can be selected.
  613. Note that WORD is evaluated after PREFIX/MAIN/SUFFIX and before MATCH and
  614. LEFT/MID/RIGHT, so you can't select a filename part with MATCH or LEFT/MID/
  615. RIGHT and then select a word within that part, but you can select a word
  616. within PREFIX/MAIN/SUFFIX.
  617.  
  618. Examples:
  619. > SRename "screen grab of game" WD 1 UP
  620. output:
  621. "screen grab of game" renamed as "SCREEN grab of game"
  622.  
  623. > SRename "Letter to john" WD -1 UP
  624. output:
  625. "Letter to john" renamed as "Letter to JOHN"
  626.  
  627. > SRename "screen grab of game" WD 1,2 UP
  628. output:
  629. "screen grab of game" renamed as "SCREEN GRAB of game"
  630.  
  631. > SRename Data:Pics/ MA WD 1 UP : Makes uppercase the first word in the main
  632. part of the filename.
  633.  
  634. > SRename Data:Pics/ MA WD 1 L 1 UP : Makes uppercase the first character of
  635. the first word in the main part of the filename.
  636.  
  637. -------------------------------------------------------------------------------
  638.  
  639. INCLSEP (IS) <number> :
  640. Makes the WORD selector to include the separating characters that are left or
  641. right of the word to select. The supplied number can be 1 or 2 and designates
  642. what separating characters should be included.
  643. 1 means that the separating characters of only one side of the word will be
  644. included: the right side. If there aren't any on the right side, then the
  645. characters on the left side will be included.
  646. 2 means that the separating characters on both sides will be inluded, if they
  647. exist.
  648. This keyword has been included mainly to aid in the deleting of words.
  649. Without INCLSEP the WORD selector will select the exact word that is told to,
  650. and in case that word is to be deleted the spaces next to that word will remain.
  651.  
  652. For example:
  653. > SRename "Bin:Picture of a ship" WD 3 DL
  654. output:
  655. "Picture of a ship" renamed as "Picture of  ship"
  656.  
  657. As you see there are two spaces between 'of' and 'ship' instead of one that
  658. would be normal. If you use INCLSEP 1 you will have:
  659.  
  660. > SRename "Bin:Picture of a ship" WD 3 IS 1 DL
  661. output:
  662. "Picture of a ship" renamed as "Picture of ship"
  663.  
  664. Now the WORD selector selects 'a ' instead of 'a' for deletion.
  665.  
  666. If you use INCLSEP 2 you will have:
  667.  
  668. > SRename "Bin:Picture of a ship" WD 3 IS 2 DL
  669. output:
  670. "Picture of a ship" renamed as "Picture ofship"
  671.  
  672. Now WORD selected ' a ' for deletion.
  673.  
  674. -------------------------------------------------------------------------------
  675.  
  676. WSEP (WS) <char(s)> :
  677. Defines the word separator that will be used by the WORD selector to pick up
  678. words. This is a space character by default.
  679. This separator can be more than one character if this is really needed.
  680.  
  681. Example:
  682. > SRename Letter_to_john WD 3 UP WS _
  683. output:
  684. "Letter_to_john" renamed as "Letter_to_JOHN"
  685.  
  686. -------------------------------------------------------------------------------
  687.  
  688. MATCH (MT) [:][/]<string(s)> :
  689. Selects the characters that match the supplied string(s).
  690. If the string to match is preceded by a colon ':' then single character mode
  691. is activated and the supplied string is treated as individual characters.
  692. This mode is now used to replace the DELCHARS action.
  693. Example:
  694. > SRename Pics/ MT :[]{}()<>#@ DELETE : Remove all []{}()<>#@ characters from
  695. the filenames in Pics.
  696.  
  697. If the match string begins with a slash '/' then character code mode is
  698. activated, and single or multiple comma separated ASCII codes or single
  699. characters should follow.
  700. Example:
  701. > SRename Data/ MT /42,> DELETE : Remove all '*' and '>' characters from the
  702. filenames in Data.
  703.  
  704. In this mode you can also select character ranges by supplying two characters
  705. or their ASCII codes which should be separated by a minus sign '-', or just
  706. the starting or ending character or ASCII code.
  707. Note that if you want to specify a range that starts lower than 10, whatever
  708. reason should you have to do that, then you must supply a leading zero before
  709. the number so that it won't be a single character, as single characters supply
  710. their ASCII value even if they are numeric ('0' gives ASCII code 48).
  711. Examples:
  712. > SRename Data/ MT /160-,48-57 DELETE : Remove all characters with ASCII codes
  713. same as or greater than 160, and ASCII codes 48 to 57 (digit characters).
  714.  
  715. > SRename Data/ MT /-.,0-9,~- TO _ : Replace with '_' all characters before '.'
  716. including it, from '0' to '9', and after '~' including it.
  717.  
  718. Note that BEFORE and AFTER have no effect in single character and character
  719. code modes, and CASESENS has no effect in character code mode.
  720. If none of the above modes are active then normal string matches are performed.
  721. Multiple strings to match can be supplied by using '|' as a separator.
  722. The matching is case-insensitive by default unless CASESENS is also given,
  723. and the supplied string cannot be a wild-card.
  724.  
  725. The MATCH selector is very powerful and in conjunction with the DO, SKIP,
  726. BEFORE, AFTER and REVMATCH keywords which are used only with MATCH and are
  727. described below, and with the LEFT-MID-RIGHT selectors, it can select any part
  728. of the filename relative to the matched string.
  729. Using BEFORE or AFTER complicates things a bit for MATCH because selected
  730. character ranges can overlap, and changes in one selected range can affect the
  731. next selected range in the way that it will be selected and in the way it will
  732. be modified.
  733. To ensure that the intended characters by the user are selected, the MATCH
  734. selector corrects both the selected character range length and position.
  735. For example if two selected character ranges overlap, and new characters were
  736. inserted within the overlapping range, then the length of the second character
  737. range is adjusted so that all the intended characters are selected.
  738.  
  739. Examples:
  740. > SRename SYS: MT pic TO picture : Replace all occurrences of 'pic' with
  741. 'picture' in all the filenames in the root dir of SYS:
  742.  
  743. > SRename Work: MT exe|lib UP : Make every occurrence of 'exe' and 'lib'
  744. uppercase in all the filenames in the root dir of Work:
  745.  
  746. -------------------------------------------------------------------------------
  747.  
  748. DO <number of matches to perform> :
  749. Determines the maximum number of matches that will be attempted by the MATCH
  750. selector. The supplied numeric value should be at least 1, as a value of 0
  751. will not result in making no matches.
  752.  
  753. Example:
  754. > SRename -new-text-file MT - TO _ DO 2: Only the first 2 occurrences of '-'
  755. will be replaced with '_'.
  756. output:
  757. "-new-text-file" renamed as "_new_text-file"
  758.  
  759. -------------------------------------------------------------------------------
  760.  
  761. SKIP (SK) <number of matches to skip> :
  762. Determines the number of matches that will be skipped before any matches can
  763. be performed.
  764.  
  765. Example:
  766. > SRename -new-text-file MT - TO _ SK 1: Only the occurrences of '-' after the
  767. first will be replaced.
  768. output:
  769. "-new-text-file" renamed as "-new_text_file"
  770.  
  771. -------------------------------------------------------------------------------
  772.  
  773. REVMATCH (RM) :
  774. Makes the matching process to start from the end of the filename, instead of
  775. the start.
  776.  
  777. Example:
  778. > SRename -new-text-file MT - DO 1 RM : Only the last occurrence of '-' will be
  779. replaced.
  780. output:
  781. "-new-text-file" renamed as "-new-text_file"
  782.  
  783. -------------------------------------------------------------------------------
  784.  
  785. BEFORE (BF) :
  786. Selects the characters before the matched string. If you want to select a
  787. limited amount of characters before a string, you should use the RIGHT selector.
  788. Note that if you use BEFORE without RIGHT to select all characters before the
  789. matched string, and start the match from the right with REVMATCH, only one
  790. match will be performed, even if more than one strings to match exist.
  791.  
  792. Examples:
  793. > SRename lastletter MT letter BF UP : Makes uppercase all characters before
  794. 'letter'.
  795. output:
  796. "lastletter" renamed as "LASTletter"
  797.  
  798. > SRename gamescreengrab MT grab BF R 6 UP : Makes uppercase 6 characters
  799. before 'grab'.
  800. output:
  801. "gamescreengrab" renamed as "gameSCREENgrab"
  802.  
  803. -------------------------------------------------------------------------------
  804.  
  805. AFTER (AF) :
  806. Selects the characters after the matched string. If you want to select a
  807. limited amount of characters after a string, you should use the LEFT selector.
  808. Note that if you use AFTER without LEFT and without REVMATCH to select all
  809. characters after the matched string, only one match will be performed, even if
  810. more than one strings to match exist.
  811.  
  812. Examples:
  813. > SRename lastletter MT last AF UP : The characters after 'last' will be made
  814. uppercase.
  815. output:
  816. "lastletter" renamed as "lastLETTER"
  817.  
  818. > SRename "the last ballad" MT " " AF L 1 UP : This is equivalent to uppercase
  819. after space, with the exception that it does not uppercase the first character.
  820. output:
  821. "the last ballad" renamed as "the Last Ballad"
  822.  
  823. > SRename readmenow MT read AF L 3,2 UP : Makes uppercase 3 characters after
  824. the end of 'read' plus 2 characters.
  825. output:
  826. "readmenow" renamed as "readmeNOW"
  827.  
  828. -------------------------------------------------------------------------------
  829.  
  830. LEFT (L) <number of chars>,[<left offset>] :
  831. Select characters from the left side of the filename.
  832.  
  833. MID (M) [<left offset>],[<right offset>] :
  834. Select characters using the distance from the left and right edge of the
  835. filename.
  836.  
  837. RIGHT (R) <number of chars>,[<right offset>] :
  838. Select characters from the right side of the filename.
  839.  
  840. Left/right offset specifies the number of characters from left/right to skip
  841. before selecting the number of characters given in the first parameter.
  842. Note that PREFIX/MAIN/SUFFIX are evaluated before LEFT/MID/RIGHT.
  843. This means that you cannot for example select the 8 rightmost characters of a
  844. file/dirname and then select the main component in them (if there is one).
  845.  
  846. For example: SRename newfilename.suf R 8 MA UP  would not select the characters
  847. 'name' but would rather select the characters 'filename' as MAIN is evaluated
  848. before RIGHT.
  849. Also if more than one component of a filename is selected, any specified
  850. actions will take place on the selected components separately.
  851.  
  852. For example: SRename 001.testpic.jpeg MA SU L 1 UP  would make uppercase the
  853. leftmost character in MAIN, and then in SUFFIX (001.Testpic.Jpeg) and not the
  854. leftmost character of MAIN and SUFFIX combined (001.Testpic.jpeg).
  855.  
  856. Examples:
  857. > SRename Libs:datatypes.library L 1 UP
  858. output:
  859. "datatypes.library" renamed as "Datatypes.library"
  860.  
  861. > SRename Work:001picture R 1,6 UP
  862. output:
  863. "001picture" renamed as "001Picture"
  864.  
  865. > SRename DataPartition_backup M 4,7 Volume
  866. output:
  867. "DataPartition_backup" renamed as "DataVolume_backup"
  868.  
  869.  
  870. *******************************************************************************
  871.                OTHER KEYWORDS THAT AFFECT COMPONENT SELECTION:
  872. *******************************************************************************
  873.  
  874. EXCLUDE (XC) :
  875. Don't modify the selected characters but those that haven't been selected.
  876. Note that it does not invert the selection that has been made by the PREFIX/
  877. MAIN/SUFFIX selectors, and that it makes the exclusion after all the selectors
  878. that have been given have acted.
  879. If for example you have used the WORD and MATCH selectors and EXCLUDE, then
  880. you can't exclude a part with WORD and then act on the excluded parts with
  881. MATCH, because EXCLUDE will act after both WORD and MATCH will have selected
  882. some parts of the filename.
  883. Also note that when EXCLUDE is given with MATCH in single character or in
  884. character code mode, then the parts that are excluded are modified as single
  885. characters rather than as strings.
  886.  
  887. Examples:
  888. > SRename asmallfile MT small UP XC
  889. output:
  890. "asmallfile" renamed as "AsmallFILE"
  891.  
  892. > SRename editorprefs L 6 UP XC
  893. output:
  894. "editorprefs" renamed as "editorPREFS"
  895.  
  896. -------------------------------------------------------------------------------
  897.  
  898. CASESENS (CS) :
  899. Make string matching case-sensitive. The default is case insensitive.
  900. This keyword can be used in conjunction with the MATCH selector,the UPDATE
  901. action, and any of the renumbering actions.
  902. Refer to these keywords for a detailed description.
  903.  
  904. Example:
  905. > SRename FileNamewithname MT name TO Comment CS
  906. output:
  907. "FileNamewithname" renamed as "FileNamewithComment"
  908.  
  909. Note that only the second occurrence of 'name' is replaced with 'Comment'
  910. because the string matching is case-sensitive.
  911.  
  912. -------------------------------------------------------------------------------
  913.  
  914. EXIST (XS) :
  915. Modify the specified component (PREFIX-MAIN-SUFFIX) only if it exists.
  916.  
  917. Example:
  918. > SRename SoundSample SU TO 8SVX XS
  919. output: SoundSample not changed
  920.  
  921. A new suffix is not appended to the filename because it didn't have one in the
  922. first place.
  923.  
  924. -------------------------------------------------------------------------------
  925.  
  926. DOT <character> :
  927. Redefine the separator character. The default separator is a period (.)
  928. The separator character determines the PREFIX-MAIN-SUFFIX components.
  929.  
  930. Example:
  931. > SRename archive_tar_gz MA SU UP DOT _
  932. output:
  933. "archive_tar_gz" renamed as "archive_TAR_GZ"
  934.  
  935.  
  936. *******************************************************************************
  937.                               ACTION KEYWORDS:
  938. *******************************************************************************
  939.  
  940. The following keywords define how the characters that have been selected with
  941. the component selector keywords, will be modified.
  942.  
  943.  
  944. TO (AS) <[path/]filename> :
  945. Replaces the selected portion of the filename with the given string.
  946. It can also be used to move files to other directories in the same volume
  947. (AmigaOS Rename function limitation) if a path is supplied.
  948. The 'TO' keyword need not be given if no other action keywords are supplied,
  949. because in such a case the last given filename activates the 'TO' action.
  950. That means that now SRename can perform simple renaming in the same manner
  951. as the original Rename command:
  952.  
  953. > SRename oldfilename newfilename : 'oldfilename' is renamed as 'newfilename'.
  954.  
  955. If however you want for example to move a file to another directory and make
  956. it uppercase, then you will have to use 'TO' as:
  957.  
  958. > SRename anyfile TO dirx/ UP : 'anyfile' is moved to 'dirx' and is made
  959. uppercase.
  960.  
  961. If you omit 'TO' as: 'SRename anyfile dirx/ UP' ,that will tell SRename
  962. to make uppercase 'anyfile' and all the filenames in the directory 'dirx'.
  963.  
  964. Note that the destination path is inherited from the source path (if it was
  965. given) so that the destination path doesn't have to be supplied with the new
  966. filename.
  967. For example if the current dir is not 'SYS:Data', to rename 'letter.txt' with
  968. the original Rename command you would type:
  969. > Rename SYS:Data/letter.txt SYS:Data/NewFileName
  970.  
  971. With SRename you just type:
  972. > SRename SYS:Data/letter.txt NewFileName.
  973.  
  974. Examples:
  975. > SRename SYS:OldFileName L 3 New
  976. output:
  977. "OldFileName" renamed as "NewFileName"
  978.  
  979. > SRename SYS:OldFileName SYS:C/ : Moves OldFileName to C: maintaining its
  980. filename.
  981.  
  982. > SRename SYS:OldFileName SYS:C/NewName : Moves OldFileName to C: and
  983. renames it as 'NewName'.
  984.  
  985. -------------------------------------------------------------------------------
  986.  
  987. UPPER (UP) :
  988. Makes the selected characters uppercase. It is Keymap sensitive so that it will
  989. function correctly with any keymap-font setup.
  990.  
  991. Example:
  992. > SRename Data/ L 1 UP : Makes uppercase the first character of every filename
  993. in 'Data'.
  994.  
  995. > SRename Data/ SU UP : Makes uppercase only the suffix of every filename in
  996. 'Data'.
  997.  
  998. -------------------------------------------------------------------------------
  999.  
  1000. LOWER (LW) :
  1001. Makes the selected characters lowercase. It is Keymap sensitive so that it will
  1002. function correctly with any keymap-font setup.
  1003.  
  1004. Example:
  1005. > SRename Data/TEXTFILE LW
  1006. output:
  1007. "TEXTFILE" renamed as "textfile"
  1008.  
  1009. -------------------------------------------------------------------------------
  1010.  
  1011. UPAFTERSPC (US) :
  1012. Makes characters after spaces uppercase. It also makes uppercase the first
  1013. character in the selected range.
  1014.  
  1015. Example:
  1016. > SRename "Data/text file" US
  1017. output:
  1018. "text file" renamed as "Text File"
  1019.  
  1020. -------------------------------------------------------------------------------
  1021.  
  1022. INSERT (IN) <string> :
  1023. Inserts the given string at the beginning of the selected characters.
  1024. You can make the insertion anywhere within the filename by using the AT
  1025. keyword.
  1026.  
  1027. Example:
  1028. > SRename Letter.txt IN First
  1029. output:
  1030. "Letter.txt" renamed as "FirstLetter.txt"
  1031.  
  1032. -------------------------------------------------------------------------------
  1033.  
  1034. AT <character position> :
  1035. Sets the position within the filename at which the string that was given with
  1036. INSERT is to be placed.
  1037. If the numeric value given with AT is negative then the character position is
  1038. measured from the right and not from the left. This is to allow AT to append
  1039. a string at the end of a filename.
  1040. Note that if the absolute value of the given character position is larger than
  1041. the length of the filename plus 1, then no insertion will take place.
  1042.  
  1043. For example: 'SRename afile IN name AT 7' will have no effect as no insertion
  1044. will be performed.
  1045.  
  1046. Also note that the AT keyword can also be used in renumbering mode to set the
  1047. position of the number within the basename.
  1048.  
  1049. Examples:
  1050. > SRename AnyFilename IN XYZ AT 4
  1051. output:
  1052. "AnyFilename" renamed as "AnyXYZFilename"
  1053.  
  1054. > SRename Sound IN Sample AT -1
  1055. output:
  1056. "Sound" renamed as "SoundSample"
  1057.  
  1058. > SRename Sound.iff IN Sample AT -5
  1059. output:
  1060. "Sound.iff" renamed as "SoundSample.iff"
  1061.  
  1062. -------------------------------------------------------------------------------
  1063.  
  1064. UPDATE (UD) :
  1065. Allows the INSERT action to proceed only if the string to insert does not exist
  1066. in the specified position.
  1067. The characters that are compared with the string to insert, are after the
  1068. specified position in insert mode and before the specified position in append
  1069. mode. The comparison is case-insensitive unless CASESENS is given.
  1070.  
  1071. Examples:
  1072. > SRename old_letter.txt IN Old UD : Because 'old' already exists in the
  1073. beginning of the filename it is not inserted.
  1074. output:
  1075. "old_letter.txt" not changed
  1076.  
  1077. > SRename old_letter.txt IN Old UD CS : Now 'Old' is inserted because the
  1078. comparison is case-sensitive.
  1079. output:
  1080. "old_letter.txt" renamed as "Oldold_letter.txt"
  1081.  
  1082. > SRename pic_last.iff IN Last AT 5 AP UD : Trying to insert 'last' 4 chars
  1083. from the end fails because it already exists.
  1084. output:
  1085. "pic_last.iff" not changed
  1086.  
  1087. -------------------------------------------------------------------------------
  1088.  
  1089. DELETE (DL) :
  1090. Removes the selected characters from the filename.
  1091.  
  1092. Examples:
  1093. > SRename SYS: L 3 DL : deletes the first 3 characters from filenames in SYS:
  1094.  
  1095. > SRename SYS: SU DL : deletes the suffix from filenames in SYS:
  1096.  
  1097. > SRename SYS: MT :#@ DL : deletes every '#' and '@' character from filenames
  1098. in SYS:
  1099.  
  1100. -------------------------------------------------------------------------------
  1101.  
  1102. SWAP (SW) :
  1103. Swaps the selected filename components. If 2 of the PREFIX,MAIN,SUFFIX
  1104. selectors are given, then the parts specified by these selectors will be
  1105. swapped. Otherwise if none of the above selectors are given, or just one, or
  1106. all of them, then just the 2 extremest components are swapped.
  1107. SWAP has an effect only on filenames with at least 2 components, like prefix-
  1108. main, main-suffix, or all (prefix-main-suffix).
  1109.  
  1110. Examples:
  1111. > SRename picture.iff SW
  1112. output:
  1113. "picture.iff" renamed as "iff.picture"
  1114.  
  1115. > SRename 001.picture.iff SW
  1116. output:
  1117. "001.picture.iff" renamed as "iff.picture.001"
  1118.  
  1119. > SRename 001.picture.iff PR MA SW
  1120. output:
  1121. "001.picture.iff" renamed as "picture.001.iff"
  1122.  
  1123. -------------------------------------------------------------------------------
  1124.  
  1125. LSHIFT (LS) :
  1126. Shifts the filename components to the left, the leftmost becomes the rightmost.
  1127. Like SWAP it has an effect only on filenames with at least 2 components.
  1128. This keyword operates on the whole filename, so the component selectors have
  1129. no effect with it.
  1130.  
  1131. Example:
  1132. > SRename SYS:001.picture.iff LS
  1133. output:
  1134. "001.picture.iff" renamed as "picture.iff.001"
  1135.  
  1136. -------------------------------------------------------------------------------
  1137.  
  1138. RSHIFT (RS) :
  1139. The opposite of LSHIFT. The rightmost component becomes the leftmost.
  1140.  
  1141. Example:
  1142. > SRename SYS:001.picture.iff RS
  1143. output:
  1144. "001.picture.iff" renamed as "iff.001.picture"
  1145.  
  1146.  
  1147. -------------------------------------------------------------------------------
  1148.  
  1149. UNIFY (UN) :
  1150. Unifies the filename components specified by PREFIX/MAIN/SUFFIX by deleting the
  1151. separator character. If no component is specified then it unifies the whole
  1152. filename.
  1153.  
  1154. Examples:
  1155. > SRename SYS:picture.001 UN
  1156. output:
  1157. "picture.001" renamed as "picture001"
  1158.  
  1159. > SRename SYS:001.picture.iff UN PR
  1160. output:
  1161. "001.picture.iff" renamed as "001picture.iff"
  1162.  
  1163. > SRename SYS:001.some.complex.name.iff UN MA
  1164. output:
  1165. "001.some.complex.name.iff" renamed as "001.somecomplexname.iff"
  1166.  
  1167. -------------------------------------------------------------------------------
  1168.  
  1169. CONV8+3 (8+3) :
  1170. Converts filenames to the MS DOS format of 8+3 characters. The filename will be
  1171. made uppercase, if it has a suffix this will be cut to 3 characters in length,
  1172. and if it has a prefix it will only be maintained if there is room left from
  1173. the main component.
  1174. Note that none of the selector keywords have any effect with this keyword,
  1175. because it always operates on the whole filename.
  1176. It is possible when converting whole directories that some filenames will fail
  1177. to be converted because they may get the same name with other files.
  1178. For example picture-1.iff and picture-2.iff will both receive the name:
  1179. PICTURE-.IFF
  1180.  
  1181. Examples:
  1182. > SRename SYS:User.prefs 8+3
  1183. output:
  1184. "User.prefs" renamed as "USER.PRE"
  1185.  
  1186. > SRename SYS:sound.sample.iff 8+3
  1187. output:
  1188. "sound.sample.iff" renamed as "S_SAMPLE.IFF"
  1189.  
  1190.  
  1191. *******************************************************************************
  1192.                                  RENUMBERING:
  1193. *******************************************************************************
  1194.  
  1195. SRename can perform intelligent renumbering of filename sequences in one go.
  1196. It is not limited in the formats it can support, as it scans the filenames for
  1197. numbers of up to 9 digits long, which can have leading zeros, and can be in
  1198. any position in the filename, or on their own.
  1199. You don't have to specify the order of renaming, normal or reverse, as with
  1200. other renumbering utilities, because it scans the filenames in the directory and
  1201. decides which way to go.
  1202. Furthermore you don't have to worry for filename clashes during renumbering,
  1203. as any clashes will be found before the actual renaming begins, and the
  1204. clashing filenames will be given temporary names, before are finally renamed.
  1205. Inverting the numbers in a sequence can also be performed, a feature that would
  1206. be useful in compiling ping-pong animations.
  1207.  
  1208. The following keywords are relevant to renumbering and can be given all at
  1209. once, or on their own :
  1210.  
  1211.  
  1212. RENUMBER (RN) <new starting number> :
  1213. Specifies the new starting number of a filename sequence. All matching
  1214. filenames will be renumbered unless an ending number is specified with UPTO.
  1215.  
  1216. Examples:
  1217. > SRename Data:picture001 RN 50 : will renumber all filenames that begin with
  1218. 'picture' and have a number attached at the end, to values starting with 50.
  1219. The leading zeros will be preserved.
  1220. output:
  1221. "picture001" renamed as "picture050"
  1222. "picture002" renamed as "picture051"
  1223. "picture003" renamed as "picture052"
  1224. "picture004" renamed as "picture053"
  1225. "picture005" renamed as "picture054"
  1226.  ....
  1227.  
  1228. > SRename Data:picture001 RN 50 UT 4 : as above but will renumber up to
  1229. filename 'picture004'.
  1230. output:
  1231. "picture001" renamed as "picture050"
  1232. "picture002" renamed as "picture051"
  1233. "picture003" renamed as "picture052"
  1234. "picture004" renamed as "picture053"
  1235.  
  1236. > SRename Data:10.frame RN 020 : will renumber all filenames that end in
  1237. '.frame' and are preceded with a value of 10 or greater, to values starting
  1238. with 020.
  1239. output:
  1240. "10.frame" renamed as "020.frame"
  1241. "11.frame" renamed as "021.frame"
  1242. "12.frame" renamed as "022.frame"
  1243. "13.frame" renamed as "023.frame"
  1244. "14.frame" renamed as "024.frame"
  1245.  ....
  1246. Note that when you supply a new starting number with leading zeros,
  1247. the old number format is overridden.
  1248.  
  1249. -------------------------------------------------------------------------------
  1250.  
  1251. UPTO (UT) <renumber up to this number> :
  1252. Specifies the existing number in a filename up to which SRename will perform
  1253. any of the renumbering actions.
  1254. If you give this keyword you must specify at least one renumber-type action
  1255. (RENUMBER,STEP,PLACES,BASENAME,AT,INVERT) with it, otherwise a 'Required
  1256. argument missing' error will occur.
  1257.  
  1258. Examples:
  1259. > SRename Data:picture001 RN 50 UT 6 : will renumber from 'picture001' up to
  1260. 'picture006'.
  1261.  
  1262. > SRename Data:frame100 UT 110 BN AnimFrame : will change the basename to
  1263. 'AnimFrame' from 'frame100' up to 'frame110'.
  1264.  
  1265. > SRename Pics/datafile0010 UT 20 PL 2 : will make 2-digit the numbers from
  1266. 'datafile0010' up to 'datafile0020'.
  1267.  
  1268. -------------------------------------------------------------------------------
  1269.  
  1270. STEP (ST) <step value> :
  1271. Defines the increment value of renumbering. The default increment is 1.
  1272. It can also take negative values.
  1273.  
  1274. Examples:
  1275. > SRename Data:picture001 RN 30 ST 2 : increases the new starting value by 2.
  1276. output:
  1277. "picture001" renamed as "picture030"
  1278. "picture002" renamed as "picture032"
  1279. "picture003" renamed as "picture034"
  1280. "picture004" renamed as "picture036"
  1281.  ....
  1282.  
  1283. > SRename Data:picture001 ST 3 : will keep the original starting value, but
  1284. will increase the destination numbers in steps of 3 :
  1285. output:
  1286. "picture004" renamed as "picture010"
  1287. "picture003" renamed as "picture007"
  1288. "picture002" renamed as "picture004"
  1289. "picture001" not changed
  1290.  ....
  1291. Note that the renumbering is executed in reverse order in order to avoid a
  1292. clash when renaming picture002 to picture004 (picture004 already exists).
  1293.  
  1294. -------------------------------------------------------------------------------
  1295.  
  1296. PLACES (PL) <places value> :
  1297. Sets the number format of the destination filenames. This affects the number of
  1298. leading zeros the numbers will have.
  1299. If you specify a places value that is smaller than the digits a number already
  1300. has, that number will be unaffected. Any numbers will less digits than the
  1301. places value will be padded with leading zeros.
  1302.  
  1303. Examples:
  1304. > SRename Data:picture001 RN 30 PL 4 : makes the numbers 4-digit.
  1305. output:
  1306. "picture001" renamed as "picture0030"
  1307. "picture002" renamed as "picture0031"
  1308. "picture003" renamed as "picture0032"
  1309. "picture004" renamed as "picture0033"
  1310.  ....
  1311.  
  1312. > SRename Data:picture001 PL 1 : strips all leading zeros from the numbers.
  1313. output:
  1314. "picture001" renamed as "picture1"
  1315. "picture002" renamed as "picture2"
  1316. "picture003" renamed as "picture3"
  1317. "picture004" renamed as "picture4"
  1318.  ....
  1319.  
  1320. > SRename Data:picture001 UT 3 PL 2 : will renumber from number 001 to 003,
  1321. and make the numbers 2-digit.
  1322. output:
  1323. "picture001" renamed as "picture01"
  1324. "picture002" renamed as "picture02"
  1325. "picture003" renamed as "picture03"
  1326.  
  1327. -------------------------------------------------------------------------------
  1328.  
  1329. INVERT (IV) :
  1330. Invert the numbers in a filename sequence. This is exactly how inverting works:
  1331.  
  1332.          original filenames              new filenames
  1333.          ------------------              -------------
  1334.             file.10        -> becomes ->   file.14
  1335.             file.11        -> becomes ->   file.13
  1336.             file.12       - not changed -
  1337.             file.13        -> becomes ->   file.11
  1338.             file.14        -> becomes ->   file.10
  1339.  
  1340. You may have noticed that executing this sequence of rename commands has a
  1341. problem: how can 'file.10' become 'file.14' when 'file.14' already exists.
  1342. SRename sees that and when destination filenames already exist, the files to
  1343. be renumbered are given temporary filenames until the existing filenames
  1344. themselves have been renumbered, so after this is done the temporary filenames
  1345. are given their normal destination filenames.
  1346. An unresolvable error occurs (New number exists) if these existing filenames
  1347. that cause clashes are not scheduled to be renumbered because they are outside
  1348. the range of files to be renumbered.
  1349.  
  1350. Examples:
  1351. > SRename Data:file100 IV : inverts the whole filename sequence.
  1352. output:
  1353. "file100" renamed as "109.srtemp861A5BC"
  1354. "file101" renamed as "108.srtemp861A5BC"
  1355. "file102" renamed as "107.srtemp861A5BC"
  1356. "file103" renamed as "106.srtemp861A5BC"
  1357. "file104" renamed as "105.srtemp861A5BC"
  1358. "file105" renamed as "file104"
  1359. "file106" renamed as "file103"
  1360. "file107" renamed as "file102"
  1361. "file108" renamed as "file101"
  1362. "file109" renamed as "file100"
  1363. "109.srtemp861A5BC" renamed as "file109"
  1364. "108.srtemp861A5BC" renamed as "file108"
  1365. "107.srtemp861A5BC" renamed as "file107"
  1366. "106.srtemp861A5BC" renamed as "file106"
  1367. "105.srtemp861A5BC" renamed as "file105"
  1368.  
  1369. Notice how numbers 100 to 104 are given temporary filenames before been finally
  1370. renumbered, because of clashes that would occur during the renaming process.
  1371.  
  1372. > SRename Data:file100 RN 50 IV : inverts the filename sequence and gives it
  1373. a starting number of 50.
  1374. output:
  1375. "file100" renamed as "file59"
  1376. "file101" renamed as "file58"
  1377. "file102" renamed as "file57"
  1378. "file103" renamed as "file56"
  1379. "file104" renamed as "file55"
  1380. "file105" renamed as "file54"
  1381. "file106" renamed as "file53"
  1382. "file107" renamed as "file52"
  1383. "file108" renamed as "file51"
  1384. "file109" renamed as "file50"
  1385.  
  1386. -------------------------------------------------------------------------------
  1387.  
  1388. BASENAME (BN) <basename string> :
  1389. Changes the filenames of a sequence but leaves the numbers that are attached
  1390. to each filename intact.
  1391. To delete the basename of a filename sequence, thus leaving only the numbers,
  1392. you should simply give: BASENAME ""
  1393.  
  1394. Examples:
  1395. > SRename Data:file100 BN picture : replaces 'file' with 'picture' in every
  1396. filename. Note that the number continues to be at the end of the new basename.
  1397. output:
  1398. "file100" renamed as "picture100"
  1399. "file101" renamed as "picture101"
  1400. "file102" renamed as "picture102"
  1401. "file103" renamed as "picture103"
  1402.  ....
  1403.  
  1404. > SRename Data:sound001.iff BN snd : will replace 'sound' with 'snd'.
  1405. output:
  1406. "sound001.iff" renamed as "snd001"
  1407. "sound002.iff" renamed as "snd002"
  1408. "sound003.iff" renamed as "snd003"
  1409. "sound004.iff" renamed as "snd004"
  1410.  ....
  1411.  
  1412. > SRename Data:file001pic RN 50 BN filepicture : will renumber starting at 50,
  1413. and replace 'filepic' with 'filepicture'. Note that the old number position
  1414. is preserved.
  1415. output:
  1416. "file001pic" renamed as "file50picture"
  1417. "file002pic" renamed as "file51picture"
  1418. "file003pic" renamed as "file52picture"
  1419. "file004pic" renamed as "file53picture"
  1420.  ....
  1421.  
  1422. > SRename Data:file001pic BN "" : will delete the basename.
  1423. output:
  1424. "file001pic" renamed as "001"
  1425. "file002pic" renamed as "002"
  1426. "file003pic" renamed as "003"
  1427. "file004pic" renamed as "004"
  1428.  ....
  1429.  
  1430. Note that when the number is surrounded by the basename, (the number is not
  1431. at the beginning or at the end) the position of the number within the basename
  1432. is preserved when a new basename is given.
  1433. This position can be changed with the use of the AT keyword as is explained
  1434. below.
  1435.  
  1436. -------------------------------------------------------------------------------
  1437.  
  1438. AT <position value> :
  1439. Sets the position of the number within the basename. It works in the same way as
  1440. with INSERT: positive values mean character position from the left and negative
  1441. values mean character position from the right.
  1442.  
  1443. Examples:
  1444. > SRename frame100.iff AT 1 : will move all numbers in the filename sequence
  1445. at the first character of the basename.
  1446. output:
  1447. "frame100.iff" renamed as "100frame.iff"
  1448. "frame101.iff" renamed as "101frame.iff"
  1449. "frame102.iff" renamed as "102frame.iff"
  1450. "frame103.iff" renamed as "103frame.iff"
  1451.  ....
  1452.  
  1453. > SRename 100frame.iff AT 6 : will move all numbers at the 6th character of
  1454. the basename.
  1455. output:
  1456. "100frame.iff" renamed as "frame100.iff"
  1457. "101frame.iff" renamed as "frame101.iff"
  1458. "102frame.iff" renamed as "frame102.iff"
  1459. "103frame.iff" renamed as "frame103.iff"
  1460.  ....
  1461.  
  1462. >SRename 100frame.iff AT -5 : all numbers will be moved at the 5th character
  1463. of the basename from the end.
  1464. output:
  1465. "100frame.iff" renamed as "frame100.iff"
  1466. "101frame.iff" renamed as "frame101.iff"
  1467. "102frame.iff" renamed as "frame102.iff"
  1468. "103frame.iff" renamed as "frame103.iff"
  1469.  ....
  1470.  
  1471. -------------------------------------------------------------------------------
  1472.  
  1473. CASESENS (CS) :
  1474. When in renumbering mode this keyword preserves each basename's casing.
  1475. If CASESENS is not given all basenames will get their content from the basename
  1476. of the first filename in the sequence, which is the default behaviour.
  1477.  
  1478. Example:
  1479. >SRename frame01 RN 20 CS
  1480. output:
  1481. "frame01" renamed as "frame20"
  1482. "FRAME02" renamed as "FRAME21"
  1483. "frame03" renamed as "frame22"
  1484. "FRAME04" renamed as "FRAME23"
  1485. "frame05" renamed as "frame24"
  1486.  
  1487. As you see the second and fourth basename remain in upper case.
  1488.  
  1489. *******************************************************************************
  1490.                                OTHER KEYWORDS:
  1491. *******************************************************************************
  1492.  
  1493. NODIROUT (NDO) :
  1494. Suppresses directory name output during recursion.
  1495.  
  1496. QUIET (Q) :
  1497. Suppresses all output including error messages.
  1498.  
  1499. -------------------------------------------------------------------------------
  1500.  
  1501.  
  1502. EMULATED FUNCTIONS :
  1503.  
  1504. You may think that SRename has some functions missing, like uppercase first
  1505. character, delete spaces, spaces to underscores, replace string1 with string2,
  1506. etc.
  1507. Such specialised functions can be built with other functions, for example:
  1508.  
  1509. Uppercase first can be performed with: LEFT 1 UP
  1510. Delete spaces with: MATCH " " DELETE
  1511. Spaces to underscores with: MATCH " " TO _
  1512. Replace string1 with string2 with: MATCH string1 TO string2
  1513.  
  1514. Even uppercase after space can be emulated with MATCH " " AFTER LEFT 1 UP, but
  1515. as the emulated function does not uppercase the first character too, I have
  1516. left the specialised function in.
  1517.  
  1518.  
  1519. PRIORITIES :
  1520.  
  1521. Not all keyword combinations make sense, that's why some keywords have priority
  1522. or cancel others. The following priorities exist:
  1523.  
  1524. LEFT has priority over MID which has priority over RIGHT
  1525. MATCH is evaluated before LEFT/MID/RIGHT
  1526. WORD is evaluated before MATCH
  1527. NODIRS cancels NOFILES
  1528. BEFORE cancels AFTER
  1529. RLEVEL has priority over RECURSE
  1530. DELETE cancels every other action
  1531. TO cancels every other action except DELETE
  1532. CONV8+3 cancels UPPER, LOWER and UPAFTERSPC
  1533. UPPER cancels LOWER and UPAFTERSPC
  1534. LSHIFT cancels RSHIFT
  1535. Any renumbering related action is cancelled by any other non-renumbering action.
  1536.  
  1537.  
  1538. TIPS:
  1539.  
  1540. When you use SRename with a filemanager like Directory Opus, and you have set
  1541. it up to receive multiple filenames ({O} option in DOpus), place that option
  1542. at the end of the command line, because if the filename sequence is too big
  1543. the arguments after it will be omitted. For example don't give DOpus the
  1544. command SRename {O} UP QUIET, but SRename UP QUIET {O}.
  1545.  
  1546. Since SRename has no way of knowing the maximum filename length that each
  1547. filesystem allows, care must be taken by the user not to supply longer
  1548. filenames than the filesystem can handle, so that filename clashes won't occur.
  1549.  
  1550. Although SRename can work with filenames that contain wildcard characters
  1551. (i.e. parentheses) and thus are recognised by the OS as file matching patterns,
  1552. it will only rename such filenames if it can find them immediately in the
  1553. supplied path.
  1554. It is not possible for example to specify such a filename and tell SRename to
  1555. recurse through the directory tree, renaming every occurrence of this filename,
  1556. if it does not find it in the starting directory, because once it can't find it
  1557. it will decide that it's a file-matching pattern, which is not what it was
  1558. intended for by you.
  1559. I advise that such filenames that confuse the OS and other applications are
  1560. not used.
  1561.  
  1562. Even if the command interface is 100% compatible with the original rename
  1563. command (version 37.2), SRename still differs in the way that it inherits
  1564. the destination path from the supplied source path.
  1565. For that reason I don't recommend that you replace the original Rename command
  1566. with SRename.
  1567.  
  1568.  
  1569. LIMITATIONS :
  1570.  
  1571. - Because of the way that the ReadArgs OS function works, you can not assign
  1572. different actions to different parts of the filename in one go, like for
  1573. example SRename anyfilename.suffix LEFT 3 UP SUFFIX DELETE.
  1574. The previous command will just delete the 3 leftmost characters from the
  1575. suffix (DELETE cancels UP).
  1576. This will change in the future.
  1577.  
  1578. - When recursing, it can go up to 255 directory levels deep.
  1579.  
  1580. - Recursing is cancelled if a destination path is given.
  1581.  
  1582. - The path of a file can't be longer than 1024 characters.
  1583.  
  1584.  
  1585. Limitations in Renumbering:
  1586.  
  1587. - Numbers in filenames from 0 to 999999999 can be handled.
  1588.  
  1589. - No wildcards can be used, and when a destination path is supplied no clash-
  1590. checking takes place (it is assumed that the destination directory contains
  1591. no filenames that can clash with the filenames that will be moved there).
  1592.  
  1593. - No filenames that contain wildcard characters can be used, because pattern-
  1594. matching is used to collect the filenames of the sequence.
  1595.  
  1596. - Any numbers that have a different format to that of the first number scanned
  1597. will not be renumbered: if the first number is 001 and 02,03 follow, these
  1598. will not be renumbered because SRename will expect to find 002 and 003.
  1599.  
  1600. - Selector keywords don't have any effect in renumbering mode.
  1601.  
  1602. - A filename clash can not be resolved if the clashing filename is outside the
  1603. range of filenames to be renumbered ('New number exists' error).
  1604.  
  1605.  
  1606. KNOWN BUGS :
  1607.  
  1608. SRename allows you to use long filenames even on filesystems that don't
  1609. support them (like FFS), so on such filesystems filenames longer than the
  1610. maximum allowed length (30 characters on FFS) will be trimmed by the
  1611. filesystem itself.
  1612. Similar behaviour can be expected for filename comments. SRename allows for
  1613. comments of up to 120 characters in length, but in the end the filesystem can
  1614. reject the comment if it's too long (up to 80 characters for FFS).
  1615.  
  1616. Although the MATCH selector performs length and position correction for the
  1617. selected character range, in case of overlapping ranges, actions that accept
  1618. position parameters are not corrected.
  1619.  
  1620.  
  1621. CREDITS :
  1622.  
  1623. Many thanks to Bill Duxbury and Fulvio Peruggi who have done beta-testing and
  1624. have reported bugs about SRename.
  1625. I also want to thank all the people who have contacted me about SRename.
  1626.  
  1627. If you have some suggestion, request, or bug report email me at:
  1628. cnicol@compulink.gr
  1629.  
  1630. or for snail-mail:
  1631.  
  1632.  Constantinos Nicolakakis
  1633.  Olympion 7 Patissia
  1634.  11143 Athens, Greece
  1635.  
  1636.